Application is a PDF or MS Word document that includes:
I think the current title of the workshop is NOT the best one to attract participants. I would greatly appreciate your suggestions for improving it.
To show the versatility of Markdown, I composed the handouts for this workshop in a Markdown document, then converted it to MS Word for final formatting and submission. The original “.md” file is available to participants from this workshop’s ABLE 2022 GitHub repository.
A. Daniel Johnson, Wake Forest University, Department of Biology, 1834 Wake Forest Road, Winston-Salem NC 27109, USA. johnsoad@wfu.edu
Scientific writing helps students learn to state problems and claims precisely, summarize evidence to support those claims, and explain their reasoning. At the 2021 ViABLE conference we presented our “six elements model” for teaching scientific writing in multi-section introductory biology courses. One of the essential elements is a standardized Scientific Writing Resource Guide that students and instructors use across multiple courses. Our Resource Guide now is available as an open-access book.
To make our Guide easier to maintain and for others to convert to their preferred formats, we wrote it using Markdown. This lightweight markup language is ideal for writing lab documents; authors can write their text once, then output it in multiple formats such as HTML5 for web pages, or Word documents for handouts. Groups of Markdown files can be converted to interactive online books. Markdown takes ~20 minutes to learn, and marked text remains readable.
Participants in this workshop do not need any technical skills beyond basic computer skills. They will learn to use Markdown by editing our Guide and by creating new pages that they will convert into formatted Word and HTML5 documents. We will demonstrate how to use R Studio to assemble collections of Markdown documents into books, and how to use GitHub to manage and share writing project files.
Participants will leave with a copy of our Scientific Writing Resource Guide that they can revise to match their course requirements, tools for writing and converting Markdown files, and a GitHub account where they can back up their project. Those interested can learn how to launch new book projects of their own, or contribute to our published edition of the Resource Guide.
Keywords: scientific writing, writing guidelines, Markdown, lab development tools, R Studio, web publishing
Scientific writing helps students learn to state problems and present claims precisely, summarize evidence to support those claims, and explain their reasoning. For many years, our Scientific Writing Resource Guide has been one of our essential tools for teaching scientific writing in multiple courses. The Guide focuses on writing a lab report that models a journal article because the same components are used in most other forms of scientific communication too. The general format conforms to the Council of Science Editors (8e) standards, with some modifications to make writing easier for students just starting out. The Guide includes sections on data visualization, basic biostatistics, and how to cite literature.
In 2021 we updated, expanded, and published our Writing Resource Guide. Our goal is to support two audiences: undergraduates learning the craft of scientific writing, and biology instructors who either teach scientific writing to undergraduates or supervise teaching assistants who do. Rather than try to make one guide meet the needs of every possible audience, we designed ours to be an evolving resource, and released it under terms of a Creative Commons BY-NC-SA 4.0 license. The Guide is written in Markdown, so users can convert the Guide to whatever format is needed. Participants in this workshop will learn how to access and modify the Resource Guide using free tools. They can edit, extend or modify our Guide as needed to fit their particular needs and requirements, so long as they attribute its original source and do not use it commercially.
Producing the shared Resource Guide introduced us to Markdown, a lightweight markup language that is extremely easy to use, and ideally suited to the challenges of writing lab documents that may have to go to multiple destinations. With Markdown, authors write a text once then convert it into multiple file formats. It takes less than 20 minutes to learn most of the Markdown syntax needed for routine writing tasks, and marked-up text is still easy to read. Markdown can be converted to HTML5 so it plays well with most LMSs. It also can be converted directly into MS Word or PDF documents. With additional free tools, collections of Markdown documents can be compiled into interactive online books.
To demonstrate the versatility of Markdown, all of the handouts for this workshop were written in Markdown, then converted it to MS Word for final formatting and submission. The original “.md” file is available to participants from this workshop’s ABLE 2022 GitHub repository.
Participants in this workshop do not need any technical skills beyond basic computer skills. The exercises assume no prior knowledge of Markdown, the other tools, or computer coding.
Before the workshop participants will need to install GitHub Desktop and register for a free GitHub account. Participants also need to install R and R Studio. We will troubleshoot any installation problems at the start of the workshop.
In the first half of the workshop participants will copy a repository containing our Resource Guide to their personal GitHub account. Then they will create and edit new Markdown documents using R Studio, and a plain text editor. Finally they will push their new files to their personal repository. In the second half of the workshop, participants will learn how to use R Studio and standalone tools to render edited pages into HTML and MS Word formats. I will demonstrate how R Studio plus Bookdown can turn a collection of Markdown files into a book that can be hosted online or printed.
Participants will leave this workshop with a complete copy of the Science Writing Resource Guide that they can revise to match their local needs, editing tools, and a personal GitHub account from which to share work with others, or launch a book project (say, a new lab manual) of their own. Participants will help us identify what additional topics should be included in the Resource Guide, and if interested, contribute new material for the Guide.
Give yourself enough time to install the software. GitHub Desktop takes 10-15 minutes to install. Registering for a new GitHub account takes 5-10 minutes. R Studio Desktop takes 10-15 minutes to install if you do not have it already.
If any installation does not work, we will troubleshoot it at the beginning of the workshop.
GitHub is a no/low cost, secure collaboration and code sharing site that is popular with data scientists and developers. GitHub also is becoming a popular hub for hosting blogs, static websites, and e-books (for example, Using Markdown inside R.) GitHub Desktop greatly simplifies installation, creating an account, and handling repositories.
Go to GitHub and follow their instructions for installing GitHub Desktop on your computer: Downloading and Installing GitHub Desktop
If you have time, take a look around the application: Getting Started With GitHub Desktop
GitHub Desktop should ask if you want to log into an existing account, or create a new one. If it does not do that automatically, go to the GitHub home page and follow the prompts to register. You do not need a private account for this workshop. If you choose to start using GitHub regularly, a private account costs $50/year. GitHub definitely is a good investment; the backup service alone saved me several times when I accidentally deleting important files.
You need to download and install R (the engine) before R Studio Desktop (the user interface) on your computer.
For more detailed instructions, consult Installing R and R Studio, Step by Step
GitHub stores collections of files related to one project in folders called repositories (aka, “repos”). When you installed GitHub, you created a dedicated spcace inside your computer for storing repositories. This is where your working copy of the Writing Resource Guide lives.
Users can create multiple repositories for different projects. Private repositories can only be seen by their owner and the GitHub users that the project owner specifies. Public repositories are available for anyone to view or copy, but they cannot add new files, or revise or remove existing files without the repository owner’s express permission.
What makes GitHub so useful is that you can make a copy of any repository you have rights to see and store it in your own GitHub account. Your copy contains all of the files that were in the project’s original repository.
There are two kinds of copies: clones, and forks. A clone is a completely independent copy. GitHub will tell you if there have been changes made to the original source repository, but those changes are not added to your copy, and any changes you make to your version do not affect the source. We usually clone repositories when we want to use the materials independently from their original authors.
A fork is a repository copy that remains connected to its parent. All of the users are working collaboratively on the same set of files at the same time. Unlike a Google document though, changes made by collaborators have to be approved by the owner of the repository. Once changes are approved, they are merged into the repository and “pushed” to all collaborators’ copies of the repository. Forked repositories are useful when multiple authors are working on one project. Every change is documented along with who made it. Individuals can work on separate files (and even different versions of the same file) without interfering with each other. Earlier versions of every file are available from the file archive.
In this exercise you will be cloning the ABLE 2022 Workshop repository. This is your sandbox copy; you cannot damage the original source files. You can edit any page or add new pages. If you make a mistake in a document and cannot fix it, just download a new copy. Later you will fork the SWP Writing Resource Guide. You’ll also be using the Commit and Push commands. Do not worry about what they mean right now; we will talk in detail about them in Exercise 3.
Use a web browser to log into your GitHub account.
Click on the URL (or type it in) to go directly to the ABLE workshop repository: https://github.com/adanieljohnson/ABLE_2022_Workshop. Alternatively, go to GitHub, look forthe Search window at the top left, and enter adanieljohnson/ABLE_2022_Workshop. This is the shortcut to the project repository.
What you see will be something similar to the screenshot below. Click on “Code” to open the window with the link to clone this repository.
Main page of ABLE Workshop repository
Orange arrow marks the URL to clone the repository.
GitHub Desktop
Committing changes to your local copy of the files.
Pushing a copy of your changes to your main GitHub account
Now that your repo is saved, we can play. Open the folder named Sample Files. It contains several .md files and the corresponding rendered HTML and MS Word formats. Open one of the .md files, pen them, then open the corresponding file with the .md extension.
Using Handout for Exercise 1 as your “.md to .html/.docx dictionary,” try to translate the markup in the .md files.
If you make any changes to your .md files, be sure to commit them before going on to Exercise 2.
Markdown was created as a way for writers to mark up text quickly to show formatting without having to embed full HTML tags. The goal with Markdown is to separate the structure of a document (headers, paragraphs, bullets, etc.) from the words of the text. By using a single set of marking conventions (called the syntax) marked-up text can be converted to dozens of different formats.
Here is some text formatted so you can see the the markup:
### Level 4 Header - Formatting
There are two main kinds of text formatting:
* Inline formatting (\_italics\_, subscripts like H\~2\~SO\~4\~, etc.)
* Block- or paragraph-level formatting (headings, sub-headings, etc.)
…and what the same text looks like rendered:
There are two main kinds of text formatting:
The table shows how to mark text, and what it will look like when rendered.
| Inline Formats | How to Mark Them | How They Appear |
|---|---|---|
| Italics | _italicized_ word | italicized word |
| *italicized* word | italicized word | |
| Bold | __bolded__ word | bolded word |
| **bolded** word | bolded word | |
| Bold Italics | ___marked___ word | marked word |
| ***marked*** word | marked word | |
| Superscripts | Super^script^ed letters | Superscripted letters |
| Subscripts | Sub~script~ letters | Subscripted letters |
| Horizontal rule | *** | Draws a line across page _____ |
| Inline code (not rendered) | `code block` | code block |
| Escape a special character | \*code block\* |
*code block* |
| Links to web pages | [text](link) |
RStudio |
| Links with URL | [link](link) |
https://www.rstudio.com |
| Links to embed local images | . |
 |
| Links to embed image from web | . |
Header levels are indicated with 1-6 hash marks followed by a space.
| Block Formats | How to Mark Them |
|---|---|
| Level 1 Header | # Level 1 Header |
| Level 2 Header | ## Level 2 Header |
| Level 3 Header | ### Level 3 Header |
| Level 4 Header | #### Level 4 Header |
| Level 5 Header | ##### Level 5 Header |
| Level 6 Header | ###### Level 6 Header |
How they render:
Regular paragraphs need to be separated by a blank line, or they will run together. For example, a text written without spacing lines like this:
There are several kinds of text formatting to explore.
Inline formatting text.
Block- or paragraph-level formatting.
Lists and quotes.
Looks like this when rendered:
There are several kinds of text formatting to explore. Inline formatting text. Block- or paragraph-level formatting. Lists and quotes.
Text written WITH spacing lines like this:
There are several kinds of text formatting to explore.
Inline formatting text.
Block- or paragraph-level formatting.
Lists and quotes.
Renders like this:
There are several kinds of text formatting to explore.
Inline formatting text.
Block- or paragraph-level formatting.
Lists and quotes.
Blockquotes are written after the “>” symbol. This text:
> "I thoroughly disapprove of duels. If a man should challenge me,
I would take him kindly and forgivingly by the hand and lead him
to a quiet place and kill him."
>
> --- Mark Twain
Renders like this:
“I thoroughly disapprove of duels. If a man should challenge me, I would take him kindly and forgivingly by the hand and lead him to a quiet place and kill him.”
— Mark Twain
Blocks for writing code that is not converted are written between three backticks. To include literal backticks, use more backticks outside.
``` Block of text or code that should NOT be rendered, like this __bold__ word. ```
Bulleted or unordered lists need to be separated from the preceding paragraph by a blank line. The items start with *, +, or -, and you can nest one list within another list by indenting the sub-list by four spaces. For consistency, it is best to make it a habit of using one character for main bullets, and the other two for sub-bullets.
A coded list looks like:
* First item
* Second item
+ First sub-item
- First sub-sub-item
- Second sub-sub-item
+ Second sub-item
* Third item
The output renders as:
Ordered list items start with numbers, but the rule for nesting are the same as for unordered lists.
1. First item
2. Second item
1. First sub-item
1. First sub-sub-item
2. Second sub-sub-item
2. Second sub-item
3. Third item
The output renders as:
The two formats can be mixed together:
1. First item
+ Sub-item
+ Sub-item
2. Second item
3. Third item
Renders as:
The challenge when using numbered lists in Markdown is that they sometimes default to starting with #1. There is no simple and consistent way to force a list to start with a particular number. I usually fix this by editing the HTML or Word document directly, or just pre-number lists myself.
Task lists are unordered lists with editable checkboxes instead of bullet marks. To create a task list with open check boxes, begin each item with a dash, space, then opening and closing square brackets separated by one space (- [ ] ) in front of task list items. To select a checkbox, add an x in between the brackets (- [x] ).
How to enter it:
- [x] Write the manual pages
- [ ] Update the LMS
- [ ] Email students
The rendered output looks like this:
Inline LaTeX equations are written using standard LaTeX syntax, and enclosed by pairs of $ signs. This code:
$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$
Renders an inline version of the equation as:
\(f(k) = {n \choose k} p^{k} (1-p)^{n-k}\)
Equations in display style are written with a pair of double dollar signs. This code:
$$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$$
Renders as:
\[f(k) = {n \choose k} p^{k} (1-p)^{n-k}\]
The first link below is for a tutorial on writing LaTeX equations. The second link is for a web page where you can write LaTeX equations using an online visual editor.
MS Word handles equation rendering well, but other Markdown formatting tools sometimes fail to render correctly. Always check any formatted equations you have in a .md file the first time you try out a new rendering tool. In practice, we usually do not need to edit equations after typing them the first time. So I usually will render them once, take a screen shot, and embed them as images. As with other steps, what keeps your workflow simple is what you should do.
There are some things that base Markdown does not handle well. For example, subscript and superscript markup may not work on the first character or number in a word (like 3H) or for a whole word. Some other useful items are not in the GHFM syntax at all. You can fill in these gaps with a few basic HTML codes.
| If you need to… | Insert this HTML snippet | For this result |
|---|---|---|
| Force a superscript for a whole word or first character | <sup>super</sup>script |
superscript |
| Force a subscript for a whole word or first character | <sub>sub</sub>script |
subscript |
| Strike through text | <strike>This</strike> word |
|
| Add an extra space between items | |
|
| Add an extra line between items | <br> |
|
| Add a horizontal rule between lines | <hr/> |
_____ |
| Add Greek letters | α, η |
α, η |
This page is a good source for other HTML shortcuts. You csan find more information about special symbols here.
These web resources can help you build your Markdown writing skills. More are listed in the Notes for Instructors.
Markdown was designed to be easy to add while writing. Unlike HTML, Markdown does not require any special code or starting text at the beginning of a new document. The only requirement is that the saved text file should have .md as the extension.
There are many ways to write Markdown files. You can:
Which will work best for you depends on your personal preferences, and how you plan to use the files. You may end up using some of all three methods. Our goal today is to introduce you to each method, so you can find a workflow that fits how you use documents most often.
Personal Tidbit: right now, most of my writing ends up on our campus LMS so it needs to be plain HTML. I write occasional handouts that need to be in MS Word (.docx) format. I prefer to write drafts in a commercial plain text editor that shows Markdown codes in color. I work across multiple computers, so even my early draft files go into a GitHub repository. That way I can access them anywhere.
When it is time to generate output, the commercial text editor I use can convert Markdown directly to plain HTML that I then can copy/paste straight into our LMS. I use R Studio to generate MS Word documents and online books. I rarely make PDFs anymore because they can be hard for screen readers to translate.
In this exercise you will try writing and editing Markdown texts using R Studio as a text editor, and a standalone text editor.
The goal of these two procedures is for you to experience for yourself how Markdown behaves in different editing environments. Usually one will feel more comfortable than the other; that is the way you should start out building your editing workflow.
Open R Studio, and choose__File > Open__ and navigate to the ABLE 2022 Workshop repository. Open to the file containing the Table of Contents page for the Writing Resource Guide.
Find 1-2 EXISTING pages you think you might want to edit or contribute to. Also find 1-2 topic that you do not see in the current pages that you think should be in the Guide.
Now open the folder named Writing Resource Guide. It contains the Markdown files (with the “.md” extension) for the full Writing Resource Guide. Locate one of the pre-existing .md files you wanted to edit, and open it.
Next you will start a new file. Choose File > New File > Markdown file.
Start a new .md file
Enter some starting text. One or two words is enough.
Save the file in your ABLE 2022 Workshop repository. Give your file a name that reflects the topic you did not see. Include the .md extension. TIP: when you name files, do not include spaces. Write all file names in CamelCase (FileName1.md) or Snake_Case (File_Name_1.md)
Now you have a starting file that you can edit any way you wish.
When you are finished editing your two pages, save them both in the ABLE 2022 Workshop respository folder.
Close R Studio for now.
Navigate to the your ABLE 2022 Workshop repository folder. Usually it is located in your Documents folder.
Click on one of the .md files in the Writing Resource Guide folder to select it. This time you want to open the file in a plain text editor.
After you have edited an existing .md file, try creating a new one from scratch. Once again, create a new file for a topic you think is missing from the Table of Contents of the Resource Guide.
When you have finished, save both of your edited .md files.
The workflow for creating and editing .md files in a browser is a bit different. These instructions only work when you are online and logged into GitHub.
In a browser, log into GitHub (not Desktop). Go to the repository containing your cloned copy of the Resource Guide. At the top of the list, click on Add file. Choose Create new file.
Give your file a name that reflects the topic you did not see. Include the .md extenstion.
Enter some starting text. One or two words is enough.
At the bottom of the page is the Commit dialog. GitHub requires you to describe what you did when you save a file. That information goes in the first box, and is required. It might seem like extra trouble at first, but when you are making changes in critical files, these commit comments can help you track what changes you made and when. If there are multiple authors working on a file, each author’s changes should say specifically what they worked on.
Commit the file directly to the master (branches and pull requests are not important until you are working on more complex projects.) TIP: when you name files, do not include spaces. Write all file names in CamelCase (FileName1.md) or Snake_Case (File_Name_1.md)
Now you have a starting file that you can edit any way you wish. If you want to see how changes to the Markdown code affect it, simply click the Preview tab at the top of the window.
Next, go back to the Table of Contents and find a page you think you might want to edit. Locate the corresponding pre-existing .md file, and open it.
You have edited and saved your .md files locally. Now the local repository on your computer is ahead of the version in your GitHub account! In this exercise we’ll synchronize the two repositories by pulling and pushing files between them.
GitHub has two functions that help you keep repositories in sync: pull (sometimes called fetch) and push. These commands can be confusing, but they are at the heart of what makes GitHub so powerful.
When you pull (or, fetch) a copy of a repository, GitHub compares the versions of the files in the repository on its servers and your local computer. If the server version does not match the local version exactly, GitHub will try to download the newer version and update the older version on your local computer. If there are newer versions in BOTH locations, GitHub will ask you to pick one to be the new “correct” version.
Say you have been editing several .md files using the text editor on your computer. When you commit the files, you are telling GitHub “these are the newest versions, and what everyone should be using from now on.” GitHub dutifully stamps them with a time and location code, and stores them locally. You need to push the files to tell the main GitHub server to update its copies.
When you push files, the server compare its copy of each file to the data stamp on the one you pushed. If there are changes in the server copy that are not in yours, GitHub will stop and tell you that you need to pull the changes already logged by the server and merge them with your local changes first. Then you can push the newest version of each file back to the server. This is a quirk of GitHub; usually pulling from the server resolves any conflicts.
Why does GitHub use so many different commands? Why not just save a file instantly and everywhere, like Google does? If you have ever had someone change a Google document you just finished editing back to what you deleted, you know why. GitHub’s strategy is designed for code writers and editors. There has to be one correct version, and one person with the authority to make the decision what files are correct. Committing a file only saves it to the local copy of the repository you happen to be working in. Pushing a file changes it on the main server, and on all of the forked copies.
Open GitHub Desktop. If you are not logged in to your account, do so now.
In the upper left of the work window, click on Current Repository. Pick the ABLE 2022 Workshop. You now should see a list of files that changed. The files you created or edited should be listed.
Setting the repository to synchronize.
In the upper part of the work window, click on Fetch Origin. This issues a Pull command; it pulls information about the server version of the repository and compares the two versions.
You should see a list of files that have changed since they were last saved to your account. Give your update a SHORT name. Then click on Commit to save the changes locally.
Committing changes to your local copy of the files.
Pushing a copy of your changes to your main GitHub account
How often should you commit and push? It is up to you, but generally you should commit every 30-60 minutes, or right after you complete major edits. You might only push changes to GitHub once or twice a day, though more often does not hurt anything. It is a good idea to push to GitHub when you finish working for the day.
Why commit so often? GitHub creates a detailed record of every Commit and Push command in your account that includes which files were changed and how. If you are editing a large file or several files and accidentally delete some important text, you can use the repository history to reconstruct the missing pieces. The more often you Commit, the finer grained the record of changes.
In Exercises 1-3 you learned how to create, edit, and manage the Markdown files. Now we are going to create documents with those files.
Markdown is converted to other document formats using Pandoc, a “universal document converter.” It can read many different document file types, then convert one format to another. Some file types get fussy when converted, but Markdown and Pandoc play very nicely together.
There are several ways to access Pandoc. You will be using a standalone web-based converter to create clean HTML, and using R Studio to create MS Word documents. I will demonstrate two other routes: using the command line to build single files, and using R Studio’s bookdown package to compile single files into an e-book.
Many plain text editors (though oddly, not R Studio) can convert Markdown to very compact plain HTML. If your text editor does not have this feature, this web-based Pandoc converter works well.
Go to the MD to HTML Converter at https://ashkanph.github.io/md-to-html/.
In the upper right corner, use Browse to find your local GitHub folder, and choose one of your recently edited .md files.
The .md file will be converted to .html and displayed.
Use the Save as HTML button to write a copy of the file in .html back to your local GitHub repository.
If you open the version of the file with the .html extension in your plain text editor, you will see it has been rewritten using HTML markup. You can copy and paste the HTML code into most LMS pages. Alternatively, you can share the file itself with others; they can open it in any web browser.
Why not use R Studio for HTML? When R Studio generates a standalone HTML preview, it embeds the raw code for every image plus a LOT of extra styling code. For example, the HTML file for the handouts for this workshop that was generated using the Ashkanph converter was 63 Kb. The same HTML file generated using R Studio was 6 Mb. This problem goes away when R Studio creates books; the HTML files are very compact, because they reference separate styling and image files rather than embedding them.
There are many free converters available. Another very good one is Markdown It, which has a very user-friendly interface, but requires copy/pasting the text rather than choosing a file. Dillinger shows the Markdown code in a window next to either the HTML code or the styled text. Rendered Markdown can be exported as HTML, but like R Studio, Dillinger includes some extra styling information.
R Studio is very good for converting .md files to well-formatted Word documents.
Open R Studio, and go to the workshop files. Open one of the files you edited or created.
At the top of the screen, open the pulldown menu next to Preview and choose Word document.
Converting Markdown to Word format
R Studio will call Pandoc, generate a pre-formatted MS Word .docx file, then save it to the same directory where the .md file is located.
Click on the .docx file to open it in MS Word.
MS Word files are formatted based on a standard template. To format documents a different way, create a template file with the header and text styles that you want. When newly generated documents are copy/pasted into the template file, the text will change to the styles you set.
It is very easy to install and run Pandoc from your computer’s command line, and it generates both .docx and .html files. If you would like to try it yourself:
Go to the Pandoc installation page for instructions to download and install to your computer.
Use the following Terminal commands to convert from .md to .html or .docx format. The commands are the same, except for the extension on the output file.
pandoc -s /filepath/Input_Filename.md -o /filepath/Output_Filename.html
pandoc -s /filepath/Input_Filename.md -o /filepath/Output_Filename.docx
Pandoc is fussier about rendering PDFs. First, it does not tolerate markup errors, and may refuse to convert a file. Second, you must install a pdf-engine then call it in the command. Look at the example below:
pandoc -s --pdf-engine=xelatex /filepath/Input_Filename.md -o /filepath/Output_Filename.pdf
The pdf-engine defines what the format will look like. This particular PDF engine’s default layout and fonts look outdated and can be hard to read. Changing them requires some deeper coding work, which is why I do not recommend using Pandoc for creating occasional PDFs. It is quicker to render a file in MS Word then save it as a PDF.
R has powerful libraries for creating online materials. The bookdown package (which uses knitr and Pandoc) combines individual .md files into full length technical books. The Home page for the R Bookdown package has examples of books that were created this way.
There is not enough time for you to set up your own GitHub-hosted book from start to finish. Instead, we’ll take a short tour through the back end of the SWP Writing Resource Guide and see how R Studio can convert a collection of separate .md files into an integrated book.
We also will talk about what is missing from the Resource Guide that you added, and your suggestions for improving it.
Today’s exercises introduced you to most of the tools you need to start using Markdown. If you want to try building your own online book, go to our Bookdown Demo repository, which is an unmodified fork of the original demo by bookdown’s creator, Yihui Yue. Clone this to a new repository, and you have a complete operating skeleton for a book. Authoring Books and Technical Documents With R Markdown describes how to customize it as you desire.
Two other books that can help you continue developing your skills are:
If you want to use our Writing Resource Guide in your own courses, you now have the original documents in your GitHub repository, and all the tools you need to edit it to suit your program needs. If you are interested in writing new material or helping us expand the Guide, let us know.
Links to packages and resources described in the workshop handouts are provided again here for convenience, along with additional resources.
Participants will need to have a laptop that can connect to the internet, and access to a web connection. Tablets are not going to work; GitHub Desktop does not work as an app. It may be helpful to have 2-3 loaner laptops in the event someone only has a tablet.
The workshop can be conducted in a computer lab, but it would be better if participants used their own computers, so they leave with the full set-up needed to continue using the materials at home.
I plan to use this section to summarize feedback and answer questions received during the workshops. Topics I expect will be covered here includes:
The working template version of the Resource Guide that participants will clone to their own accounts for editing, a copy of the .md file used to create the handouts, and all other files for the workshop will be available from the workshop’s public GitHub repository.
Participants will learn to use Markdown, GitHub and GitHub Desktop, and Pandoc text converter in the context of a collaborative writing project.
Markdown is a lightweight but very versatile text markup language that lets authors write well-structured texts once then reuse them multiple ways. It is extremely easy to learn (<20 minutes for 90% of what you will use routinely), and text with Markdown tags remains easy to read. I estimate that >80% of the new materials I write now start out in Markdown.
There are several “flavors” of the original Markdown language standard. I chose the GitHub “flavor” of Markdown (GHFM) for the workshop because:
GitHub is best known as a place where data scientists share code, but it works equally well as a no/low cost, secure project space that operates seamlessly between institutions. GitHub also is becoming a destination for hosting blogs, static websites, and open-access book projects.
Many ABLE members already know R and R Studio, but likely think of them more as a platform for statistics and numerical data analysis. When combined with GitHub and Markdown, R Studio becomes a powerful text editor, integrated development environment, and project management space.
Prior to the workshop, participants will register for a free GitHub account and connect GitHub Desktop to their GitHub account. They also will install R and R Studio. These installations are straightforward, but in the event participants have trouble, they can work with a partner while we complete their setup in the first few minutes of the workshop.
During the first 60 minutes of the workshop, participants will copy the text files for the Writing Resource Guide from a sandboxed repository I have set up for this workshop to their personal GitHub accounts. Using both R Studio and a plain text editor, they will edit an existing page, then create a new page for a topic they think is needed. By break time, participants will have completed their writing and saved their modified files back to their personal accounts.
After the break (assuming 30 minutes), participants will spend the next 60 minutes converting their edited Markdown pages into well-structured documents. They will learn to generate files in two formats:
There is not enough time to set up a complete GitHub-hosted book. Instead, I will use the remaining ~30 minutes to demonstrate how R Studio’s knitr and bookdown R libraries can compile individually edited pages into a GitHub-hosted e-book.
Participants will leave with a complete copy to our Science Writing Resource Guide which they can use in their courses. Their computer will be set up and ready to use GitHub Desktop and R Studio to continue editing their copy of the Guide, and they will have a GitHub account that they can use to build books or share pages with others. They also will have the resources needed to convert their work into MS Word or HTML documents.